<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Introduction: The Manual, etc.   I.NTRO -->
<div class='chapter' id='1'>1. Introduction</div><div class='section' id='1.1'>1.1 General Information</div>
	The Lisp Machine is a new computer system designed to provide
a high performance and economical implementation of the Lisp language. 
It is a personal computation system, which means that processors and
main memories are not time-multiplexed: each person gets his own for
the duration of the session.  It is designed this way to relieve the
problems of the running of large Lisp programs on time-sharing
systems.  Everything on the Lisp Machine is written in Lisp, including
all system programs; there is never any need to program in machine
language.  The system is highly interactive.

<!-- This seems not to be true currently -->
	This document is intended to serve both as a User's Guide and
as a Reference Manual for the language and the Lisp Machine itself. 
It is hoped that anyone with some previous programming experience (not
necessarily in Lisp) could learn all about the Lisp language and the
Lisp Machine from this manual.

	This is a <!-- open: 1, close: 0 --><font class="italic">preliminary</font><!-- open: 1, close: 1 --> <!-- MATCHED MATCHED MATCHED --> version of the Manual.  The authors
are well aware that several sections are missing.  Some small sections
were left out in the interest of publishing a manual as quickly
as possible.  Several full chapters have not been written because the
corresponding software has not settled down enough for a meaningful
document to be written; these include chapters on the Chaos network,
the mouse, and menus.  Many more major software changes are expected
in both the language and the system; this manual is far from the last word.

	The Lisp Machine executes a new dialect of Lisp called Lisp
Machine Lisp, developed at the M.I.T.<u><font color='green'>SAIL</font></u> Artificial Intelligence
Laboratory for use in artificial intelligence research and related
fields.  It is closely related to the Maclisp dialect, and attempts to
maintain a good degree of compatibility with Maclisp, while also
providing many improvements and new features.  Maclisp, in turn, is
based on Lisp 1.5. 

<div class='section' id='1.2'>1.2 Structure of the Manual</div>
	This manual attempts to document both the dialect of Lisp used
on the Lisp Machine, and the system itself.  The manual starts out with
an explanation of the language.  Chapter 2 presents some basic <!-- open: 2, close: 1 --><font class="italic">predicate</font><!-- open: 2, close: 2 --> <!-- MATCHED MATCHED MATCHED -->
functions, Chapter 3 explains the process of evaluation, and Chapter 4
introduces the basic Lisp control structures.

	Next, in Chapters 4 through 12, various Lisp data types are presented,
along with functions for manipulating objects of those types.  These nine
chapters discuss list structure, symbols, numbers, strings, arrays, closures,
stacks, and locatives.

	Chapter 13 explains the "subprimitive" functions, which are primarily
useful for implementation of the Lisp language itself and the Lisp Machine's
"operating system".  Chapter 14 explains <!-- open: 3, close: 2 --><font class="italic">areas</font><!-- open: 3, close: 3 --> <!-- MATCHED MATCHED MATCHED -->, which give
the programmer control over storage and locality of reference.

	Chapter 15 discusses the Lisp compiler, which converts Lisp programs
into "machine language".  Chapter 16 explains the Lisp macro facility, which
allows users to write their own extensions to Lisp, and Chapter 17 goes into
detail about one such extension that provides <!-- open: 4, close: 3 --><font class="italic">structures</font><!-- open: 4, close: 4 --> <!-- MATCHED MATCHED MATCHED -->.

	Chapter 18 explains the Lisp Machine's Input/Output system, including
<!-- open: 5, close: 4 --><font class="italic">streams</font><!-- open: 5, close: 5 --> <!-- MATCHED MATCHED MATCHED --> and the <!-- open: 6, close: 5 --><font class="italic">printed representation</font><!-- open: 6, close: 6 --> <!-- MATCHED MATCHED MATCHED --> of Lisp objects.  Chapter 19
describes the <!-- open: 7, close: 6 --><font class="italic">package</font><!-- open: 7, close: 7 --> <!-- MATCHED MATCHED MATCHED --> system, which allows many name spaces within
a single Lisp environment.  Chapter 20 talks about how files from a file
system are used from Lisp.

	Chapter 21 discusses the <!-- open: 8, close: 7 --><font class="italic">job system</font><!-- open: 8, close: 8 --> <!-- MATCHED MATCHED MATCHED -->, which allows shared access
to the TV screen, and multiple processes.  Chapter 22 goes into detail on
the TV display itself.  Chapter 23 explains how exceptional conditions (errors)
can be handled by programs, handled by users, and debugged.  Chapter 24
contains other miscellaneous functions and facilities.


<div class='section' id='1.3'>1.3 Notational Conventions and Helpful Notes</div>	There are several conventions of notation, and various points
that should be understood before reading the manual, particularly the
reference sections, to avoid confusion.
<!-- The reference sections are the ONLY sections? -->

	Most numbers shown are in octal radix (base eight).  Spelled out
numbers and numbers followed by a decimal point are in decimal.  This is
because, by default, Lisp Machine Lisp types out numbers in base 8; don't
be surprised by this.  To change it, see the documentation on the symbols
<!-- open: 9, close: 8 --><font class="lisp">ibase</font><!-- open: 9, close: 9 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 10, close: 9 --><font class="lisp">base</font><!-- open: 10, close: 10 --> <!-- MATCHED MATCHED MATCHED --> (<font color='red'>LINK:(</font>ibase-var)).

	The symbol " =&gt; " will be used to indicate evaluation in
examples.  Thus, when you see " <!-- open: 11, close: 10 --><font class="lisp">foo</font><!-- open: 11, close: 11 --> <!-- MATCHED MATCHED MATCHED --> =&gt; <!-- open: 12, close: 11 --><font class="lisp">nil</font><!-- open: 12, close: 12 --> <!-- MATCHED MATCHED MATCHED -->", this means the
same thing as "the result of evaluating <!-- open: 13, close: 12 --><font class="lisp">foo</font><!-- open: 13, close: 13 --> <!-- MATCHED MATCHED MATCHED --> is (or would have
been) <!-- open: 14, close: 13 --><font class="lisp">nil</font><!-- open: 14, close: 14 --> <!-- MATCHED MATCHED MATCHED -->". 

	All uses of the phrase "Lisp reader", unless further qualified,
refer to the part of Lisp which reads characters from I/O streams
(the <!-- open: 15, close: 14 --><font class="lisp">read</font><!-- open: 15, close: 15 --> <!-- MATCHED MATCHED MATCHED --> function), and not the person reading this manual.

	There are several terms which are used widely in other
references on Lisp, but are not used much in this document since they have become
largely obsolete and misleading.  For the benefit of those who may
have seen them before, they are: "S-expression", which means a Lisp
object;  "Dotted pair", which means a cons, and "Atom", which means,
roughly, symbols and numbers and sometimes other things, but not
conses. 
<p class='cindent'><!-- "S-expression" -->
<p class='cindent'><!-- "dotted pair" -->
<p class='cindent'><!-- "atom" -->

	The characters acute accent (<!-- open: 16, close: 15 --><font class="lisp">'</font><!-- open: 16, close: 16 --> <!-- MATCHED MATCHED MATCHED -->) (also called "single quote") and
semicolon (<!-- open: 17, close: 16 --><font class="lisp">;</font><!-- open: 17, close: 17 --> <!-- MATCHED MATCHED MATCHED -->) have special meanings when typed to Lisp; they are
examples of what are called <!-- open: 18, close: 17 --><font class="italic">macro characters</font><!-- open: 18, close: 18 --> <!-- MATCHED MATCHED MATCHED -->.  Though the
mechanism of macro characters is not of immediate interest to the new
user, it is important to understand the effect of these two, which are
used in the examples.
	When the Lisp reader encounters a "&thinsp;<!-- open: 19, close: 18 --><font class="lisp">'</font><!-- open: 19, close: 19 --> <!-- MATCHED MATCHED MATCHED -->&thinsp;", it reads in the next
Lisp object and encloses it in a <!-- open: 20, close: 19 --><font class="lisp">quote</font><!-- open: 20, close: 20 --> <!-- MATCHED MATCHED MATCHED --> special form.  That
is, <!-- open: 21, close: 20 --><font class="lisp">'foo-symbol</font><!-- open: 21, close: 21 --> <!-- MATCHED MATCHED MATCHED --> turns into <!-- open: 22, close: 21 --><font class="lisp">(quote foo-symbol)</font><!-- open: 22, close: 22 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 23, close: 22 --><font class="lisp">'(cons 'a 'b)</font><!-- open: 23, close: 23 --> <!-- MATCHED MATCHED MATCHED -->
turns into <!-- open: 24, close: 23 --><font class="lisp">(quote (cons (quote a) (quote b)))</font><!-- open: 24, close: 24 --> <!-- MATCHED MATCHED MATCHED -->.  The reason
for this is that "<!-- open: 25, close: 24 --><font class="lisp">quote</font><!-- open: 25, close: 25 --> <!-- MATCHED MATCHED MATCHED -->" would otherwise have to be typed in very
frequently, and would look ugly.
	The semicolon is used as a commenting character.  When the
Lisp reader sees one, the remainder of the line is
discarded.
	The character "<!-- open: 26, close: 25 --><font class="lisp">/</font><!-- open: 26, close: 26 --> <!-- MATCHED MATCHED MATCHED -->" is used for quoting strange characters so
that they are not interpreted in their usual way by the Lisp reader,
but rather are treated the way normal alphabetic characters are treated.
So, for example, in order to give a "<!-- open: 27, close: 26 --><font class="lisp">/</font><!-- open: 27, close: 27 --> <!-- MATCHED MATCHED MATCHED -->" to the reader, you must type "<!-- open: 28, close: 27 --><font class="lisp">//</font><!-- open: 28, close: 28 --> <!-- MATCHED MATCHED MATCHED -->",
the first "<!-- open: 29, close: 28 --><font class="lisp">/</font><!-- open: 29, close: 29 --> <!-- MATCHED MATCHED MATCHED -->" quoting the second one.  When a character
is preceeded by a "<!-- open: 30, close: 29 --><font class="lisp">/</font><!-- open: 30, close: 30 --> <!-- MATCHED MATCHED MATCHED -->" it is said to be <!-- open: 31, close: 30 --><font class="italic">slashified</font><!-- open: 31, close: 31 --> <!-- MATCHED MATCHED MATCHED -->.  Slashifying
also turns off the effects of macro characters such as "&thinsp;<!-- open: 32, close: 31 --><font class="lisp">'</font><!-- open: 32, close: 32 --> <!-- MATCHED MATCHED MATCHED -->&thinsp;" and "<!-- open: 33, close: 32 --><font class="lisp">;</font><!-- open: 33, close: 33 --> <!-- MATCHED MATCHED MATCHED -->".
	The following characters also have special meanings,
and may not be used in symbols without slashification.  These characters
are explained in detail in the section on printed-representation
(<font color='red'>LINK:(</font>reader)).
<table>
<tr valign='top'>
<td><font class='lisp'> "</font></td><td>String quote
</td></tr>
<tr valign='top'>
<td><font class='lisp'> #</font></td><td>Introduces miscellaneous reader macros
</td></tr>
<tr valign='top'>
<td><font class='lisp'> ,</font></td><td>See <!-- open: 34, close: 33 --><font class="lisp">`</font><!-- open: 34, close: 34 --> <!-- MATCHED MATCHED MATCHED -->
</td></tr>
<tr valign='top'>
<td><font class='lisp'> :</font></td><td>Package prefix
</td></tr>
<tr valign='top'>
<td><font class='lisp'> `</font></td><td>List structure construction
</td></tr>
<tr valign='top'>
<td><font class='lisp'> |</font></td><td>Symbol quoter
</td></tr>
<tr valign='top'>
<td><font class='lisp'> &otimes;</font></td><td>Octal escape
</td></tr><!-- item_ --></table><!-- end table -->


	All Lisp code in this manual is written in lower case.
In fact, the reader turns all symbols into upper-case, and consequently
everything prints out in upper case.  You may write programs in whichever
case you prefer.

	By convention, all "keyword" symbols in the Lisp machine system
have names starting with a colon (<!-- open: 35, close: 34 --><font class="lisp">:</font><!-- open: 35, close: 35 --> <!-- MATCHED MATCHED MATCHED -->).  The colon character is not
actually part of the print name, but is a package prefix indicating
that the symbol belongs to the package with a null name, which means
the <!-- open: 36, close: 35 --><font class="lisp">user</font><!-- open: 36, close: 36 --> <!-- MATCHED MATCHED MATCHED --> package.  If you are not using packages, that is, you are
doing everything in the <!-- open: 37, close: 36 --><font class="lisp">user</font><!-- open: 37, close: 37 --> <!-- MATCHED MATCHED MATCHED --> package, it is not necessary to type the
colon.  However, it is recommended that you always put in the colon so
that you will not have problems if you later put your program into a
package.  But it is necessary to leave out the colon in programs that
must run in both Maclisp and Lisp Machine Lisp.   The colon can usually
be omitted when you are simply typing at the top-level of Lisp, since
your typein is being read in the <!-- open: 38, close: 37 --><font class="lisp">user</font><!-- open: 38, close: 38 --> <!-- MATCHED MATCHED MATCHED --> package, but it is better to type
it so you will get used to it.  In this manual the colon will always
be included.

	Lisp Machine Lisp is descended from Maclisp, and a good deal
of effort was gone through to try to allow Maclisp programs to run
in Lisp Machine Lisp.  There is an extensive section explaining the
differences between the dialects, and how to convert Maclisp programs
to work in the Lisp Machine.  For the new user, it is important
to note that many functions herein exist solely for Maclisp compatibility;
they should <!-- open: 39, close: 38 --><font class="italic">not</font><!-- open: 39, close: 39 --> <!-- MATCHED MATCHED MATCHED --> be used in new programs.  Such functions are
clearly marked in the text.

	The Lisp Machine character set is not quite the same as that used
on I.T.S. nor on Multics; it is described in all detail elsewhere
in the manual.  The important thing to note for now is that the
character "newline" is the same as "return", and is represented by
the number 215 octal.

	When the text speaks of "typing Control-Q" (for example),
this means to hold down the CTRL key on the keyboard (either of
the two), and, while holding it down, to strike the "Q" key.
Similarly, to type "Meta-P", hold down either of the META keys
and strike "P".  To type "Control-Meta-T" hold down both CTRL
and META.  Unlike the PDP-10, there are no "control characters"
in the character set; Control and Meta are merely things
that can be typed on the keyboard.

	Many of the functions refer to "areas".  The <!-- open: 40, close: 39 --><font class="italic">area</font><!-- open: 40, close: 40 --> <!-- MATCHED MATCHED MATCHED --> feature
is only of interest to writers of large systems, and can be safely
disregarded by the casual user.  It is described elsewhere.
<!-- eof -->
</body>
</html>

